---
title: Introduction
description: Getting started with @embedpdf/engines - high-level PDF rendering engines for browser and Node.js environments
---

# @embedpdf/engines

`@embedpdf/engines` is a high-performance JavaScript library for rendering and manipulating PDF files. Built on the robust PDFium engine compiled to WebAssembly, it provides a simple, modern API that works everywhere—from the browser to the server.

## Quick Start

The best way to use the engine in a browser is with a Web Worker to keep the main thread free. Here's a complete example of rendering the first page of a PDF:

**1. Create your worker (`webworker.ts`):**
```typescript
import { PdfiumEngineRunner, DEFAULT_PDFIUM_WASM_URL } from '@embedpdf/engines';

async function init() {
  const response = await fetch(DEFAULT_PDFIUM_WASM_URL);
  const wasmBinary = await response.arrayBuffer();
  const runner = new PdfiumEngineRunner(wasmBinary);
  runner.prepare();
}

init();
````

**2. Use the engine in your app (`main.ts`):**

```typescript
import { WebWorkerEngine } from '@embedpdf/engines/worker';

const worker = new Worker(new URL('./webworker.ts', import.meta.url), { 
  type: 'module' 
});
const engine = new WebWorkerEngine(worker);

// Initialize the engine
await engine.initialize().toPromise();

// Open a document and render its first page
const document = await engine
  .openDocumentUrl({ id: 'demo', url: '/demo.pdf' })
  .toPromise();

const imageBlob = await engine
  .renderPage(document, document.pages[0])
  .toPromise();

// You can now display the image
const imageUrl = URL.createObjectURL(imageBlob);
document.getElementById('my-image').src = imageUrl;
```

## Core Features

  - **Universal:** Run the same code in web browsers (using Web Workers for performance), Node.js, and serverless functions.
  - **High-Level API:** Forget the complexities of WASM. The engine provides a clean, asynchronous API for common tasks like rendering pages, extracting text, and managing annotations.
  - **Fully Typed:** Written entirely in TypeScript for excellent autocompletion and type safety in your projects.
  - **Worker-Optimized:** Built from the ground up to offload heavy PDF processing from the main UI thread, ensuring your app stays fast and responsive.

## Framework Integrations

While `@embedpdf/engines` is framework-agnostic, we provide helpers to make integration seamless with popular frameworks.

### React

For React applications, the `usePdfiumEngine` hook is the recommended way to manage the engine's lifecycle. It handles initialization and cleanup automatically within your components.

➡️ **Learn more in the [Using with React](./react-integration.md) guide.**

### Vue

For Vue 3 applications, we provide a `usePdfiumEngine` composable that ties the engine's lifecycle to your component, providing reactive state for loading and errors.

➡️ **Learn more in the [Using with Vue](./vue-integration.md) guide.**

## Installation

```sh npm2yarn
npm i @embedpdf/engines @embedpdf/pdfium
```

## Usage Patterns

While a Web Worker is recommended for browsers, the engine is flexible and supports other environments.

### 1\. Main Thread (Browser)

For simpler use cases, you can run the engine directly on the main thread.

```typescript
import { init, DEFAULT_PDFIUM_WASM_URL } from '@embedpdf/pdfium';
import { PdfiumEngine } from '@embedpdf/engines/pdfium';

const response = await fetch(DEFAULT_PDFIUM_WASM_URL);
const wasmBinary = await response.arrayBuffer();
const pdfium = await init({ wasmBinary });

const engine = new PdfiumEngine(pdfium);
await engine.initialize().toPromise();
// ... use engine methods
```

### 2\. Node.js

The engine works seamlessly in Node.js. You'll need to provide an image conversion library like `sharp`.

```typescript
import { readFile, writeFile } from 'fs/promises';
import sharp from 'sharp';
import { init } from '@embedpdf/pdfium';
import { PdfiumEngine } from '@embedpdf/engines/pdfium';
import { createNodeImageDataToBufferConverter } from '@embedpdf/engines/converters';

const imageDataConverter = createNodeImageDataToBufferConverter(sharp);
const pdfiumInstance = await init();
const engine = new PdfiumEngine(pdfiumInstance, {
  imageDataConverter
});
await engine.initialize().toPromise();

const pdfBuffer = await readFile('document.pdf');
const document = await engine
  .openDocumentBuffer({ id: 'sample', content: pdfBuffer })
  .toPromise();

const imageBuffer = await engine
  .renderPage(document, document.pages[0])
  .toPromise();
  
await writeFile('output.webp', imageBuffer);
```